<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"
	  xmlns:ui="http://java.sun.com/jsf/facelets"
	  xmlns:h="http://java.sun.com/jsf/html"
	  xmlns:f="http://java.sun.com/jsf/core"
	  xmlns:a4j="http://richfaces.org/a4j"
	  xmlns:rich="http://richfaces.org/rich">
<ui:composition template="/templates/component-sample.xhtml">
	<ui:define name="sample">


		<p>a4j:poll is one of the way how you can organize the periodical polling of server data and
			updating the page. a4j:poll is a standard RichFaces Ajax component. Thus, you can use the same
			approach as for a4j:commandButton for example. I.e. you can use action attribute to invoke the
			action method and reRender attribute to update area(s) on the client when Ajax Response returns
			back. RichFaces uses the standard form based request, so the form around the
			a4j:poll component is required.
		</p>

		<p>The following example shown how the date and time is updated on the page based on the data
			taken from the server. To turn off polling, press "Stop Polling" button.</p>
		<p><b>Note: </b>polling is automatically disabled in this demo after one minute of working.</p>

		<div class="sample-container">

				<ui:include src="/richfaces/poll/examples/clock.xhtml"/>
				<ui:include src="/templates/include/sourceview.xhtml">
					<ui:param name="sourcepath" value="/richfaces/poll/examples/clock.xhtml"/>
				</ui:include>				
		</div>
		

		<p><b>interval</b> attribute defines the interval in ms between the previous response and the
			next request. Hence, the total period between two requests generated by a4j:poll is a sum of interval
			and server response time.
		</p>

		<p>
			<b>timeout</b> attribute defines the time in ms for how long the the client will wait for the server response.
			if Ajax Response does not come during this period, the connection is aborted and the next
			request is sent. By default, the timeout is not set.
		</p>

		<p>
			<b>enabled</b> attribute defines should the a4j:poll send request or not. You can use EL
			to point to the bean property that will be the flag. Re-render the a4j:poll component itself
			to apply the current value. See the example how to accomplish this task.
		</p>
		<p>
			a4j:poll sends requests in parallel with user activities. The intersections
			between a4j:poll Ajax requests and other Ajax requests are possible. This might causes
			unpredictable glitches. Especially, it is true for the earlier version of JSF implementations
			when the parallel requests to the server was not expected. To avoid the problem, try to follow
			very simple rules:
		</p>
		<ul>
			<li>Have a separate form for a4j:poll. Note, that other fields will be included in
				request and processed on the server if the form contains not only a4j:poll;
			</li>
			<li>Surround a4j:poll with a4j:region. This allow to limit the part of the component
				tree that will be processed for each Ajax request;
			</li>
			<li>Try to avoid updating the same server data that might be updated by the Ajax requests
				produced by the user activities. If you need this, be sure your code allows to access
				the data from parallel thread without conflicts;
			</li>
			<li>Try to avoid re-rendering the area(s) with input field and other form controls.
				This causes the losing of input focus because the old elements are removed before
				the update with the upcomming ones
			</li>
			<li>Try to re-render as little area(s) on the client as possible. Try do not have
				intersections between the areas re-rendered by a4j:poll and areas re-rendered
				by other Ajax components;
			</li>
			<li>Use the eventsQueue with the same name as the name for other Ajax components.
				This allows to queue the Ajax request and avoid updating the server side data
				and re-rendering the page area(s) in parallel;
			</li>
			<li>Set the reasonable interval. Note that each Ajax request restores the session
				and a component tree as well as processes the whole JSF lifecycle. Too often requests
				just degrade the overall performance of an application
			</li>
		</ul>


	</ui:define>

</ui:composition>
</html>
